home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat5 / cpuset.z / cpuset
Encoding:
Text File  |  2002-10-03  |  16.8 KB  |  397 lines
  1.  
  2.  
  3.  
  4. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      cpuset - overview of cpusets
  10.  
  11. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      A cpuset is a named set of CPUs, which may be defined to be restricted or
  13.      open.  A restricted cpuset only allows processes that are members of the
  14.      cpuset to run on the set of CPUs.  An open cpuset allows any process to
  15.      run on its cpus, but a process that is a member of the cpuset can only
  16.      run on the CPUs belonging to the cpuset.
  17.  
  18.      A principal use of cpusets is to create a partition of CPUs within a
  19.      larger system.  By doing this, a set of processes can be contained to
  20.      specific CPUs, reducing the amount of interaction those processes have
  21.      with other work on the system.  In the case of a restricted cpuset, the
  22.      processes that are attached to that cpuset will not be affected by other
  23.      work on the system; only those processes attached to the cpuset can be
  24.      scheduled to run on the CPUs assigned to the cpuset.  An open cpuset can
  25.      be used to restrict processes to a set of CPUs so that the affect these
  26.      processes have on the rest of the system is minimized.
  27.  
  28.      There are currently two methods in which to use cpusets: the _cccc_pppp_uuuu_ssss_eeee_tttt(1)
  29.      command, and the cpuset library (see THE CPUSET LIBRARY section below).
  30.  
  31.      For information on how to use cpusets in a Trusted IRIX environment, see
  32.      the _cccc_pppp_uuuu_ssss_eeee_tttt(1) man page.
  33.  
  34. TTTTHHHHEEEE CCCCPPPPUUUUSSSSEEEETTTT CCCCOOOOMMMMMMMMAAAANNNNDDDD
  35.      The _cccc_pppp_uuuu_ssss_eeee_tttt command is used to create and destroy cpusets, to retrieve
  36.      information about existing cpusets, and to attach a process and all of
  37.      its children to a cpuset.
  38.  
  39.      The _cccc_pppp_uuuu_ssss_eeee_tttt command uses a cpuset configuration file and a name (see
  40.      _cccc_pppp_uuuu_ssss_eeee_tttt(4) for a definition of the file format).  The cpuset configuration
  41.      file is used to define the CPUs that are members of the cpuset.  It also
  42.      contains additional parameters required to define the cpuset.  A cpuset
  43.      name is between three and eight characters long; names of two or less
  44.      characters are reserved.
  45.  
  46.      The file permissions of the configuration file define access to the
  47.      cpuset.  When permissions need to be checked, the current permissions of
  48.      the file are used.  It is therefore possible to change access to a
  49.      particular cpuset without having to tear it down and recreate it, simply
  50.      by changing the access permissions.  Read access allows a user to
  51.      retrieve information about a cpuset while execute permission allows the
  52.      user to attach a process to the cpuset.
  53.  
  54.      For additional information concerning the _cccc_pppp_uuuu_ssss_eeee_tttt command, consult the
  55.      _cccc_pppp_uuuu_ssss_eeee_tttt(1) manual page.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  71.  
  72.  
  73.  
  74. THE CPUSET LIBRARY
  75.      The cpuset library provides interfaces that allow a programmer to create
  76.      and destroy cpusets, retrieve information about existing cpusets, to
  77.      attach a process and all of its children to a cpuset, and to attach or
  78.      detach a specific process identified by its PID to or from a cpuset.
  79.  
  80.      The cpuset library requires that a permission file be defined for a
  81.      cpuset that is created.  The permissions file may be an empty file, since
  82.      it is only the file permissions for the file that define access to the
  83.      cpuset.  When permissions need to be checked, the current permissions of
  84.      the file are used.  It is therefore possible to change access to a
  85.      particular cpuset without having to tear it down and recreate it, simply
  86.      by changing the access permissions.  Read access allows a user to
  87.      retrieve information about a cpuset while execute permission allows the
  88.      user to attach a process to the cpuset.
  89.  
  90.      The cpuset library is provided as a N32 DSO library.  The library file is
  91.      _llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo, and it is normally located in the directory _////_llll_iiii_bbbb_3333_2222.  Users
  92.      of the library must include the _cccc_pppp_uuuu_ssss_eeee_tttt_...._hhhh header file which is located in
  93.      _////_uuuu_ssss_rrrr_////_iiii_nnnn_cccc_llll_uuuu_dddd_eeee.  The function interfaces provided in the cpuset library are
  94.      declared as optional interfaces to allow for backwards compatibility as
  95.      new interfaces are added to the library.  This library is only available
  96.      on IRIX 6.5.8 and later versions.
  97.  
  98.      It is possible to compile and run a program that uses this DSO and its
  99.      interfaces if they are available, but continues to execute if they are
  100.      missing. To do this, a replacement library for _llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo must be
  101.      created.  An example of how to create a replacement library is provided
  102.      in the EXAMPLES section.
  103.  
  104.      The function interfaces within the cpuset library include:
  105.  
  106.      _cccc_pppp_uuuu_ssss_eeee_tttt_CCCC_rrrr_eeee_aaaa_tttt_eeee(3x)
  107.           Create a cpuset
  108.  
  109.      _cccc_pppp_uuuu_ssss_eeee_tttt_AAAA_tttt_tttt_aaaa_cccc_hhhh(3x)
  110.           Attach the current process to a cpuset
  111.  
  112.      _cccc_pppp_uuuu_ssss_eeee_tttt_AAAA_tttt_tttt_aaaa_cccc_hhhh_PPPP_IIII_DDDD(3x)
  113.           Attach a specific process to a cpuset
  114.  
  115.      _cccc_pppp_uuuu_ssss_eeee_tttt_DDDD_eeee_tttt_aaaa_cccc_hhhh_AAAA_llll_llll(3x)
  116.           Detach all threads from a cpuset
  117.  
  118.      _cccc_pppp_uuuu_ssss_eeee_tttt_DDDD_eeee_tttt_aaaa_cccc_hhhh_PPPP_IIII_DDDD
  119.           Detach a specific process from a cpuset
  120.  
  121.      _cccc_pppp_uuuu_ssss_eeee_tttt_DDDD_eeee_ssss_tttt_rrrr_oooo_yyyy(3x)
  122.           Destroy a cpuset
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  137.  
  138.  
  139.  
  140.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_CCCC_PPPP_UUUU_CCCC_oooo_uuuu_nnnn_tttt(3x)
  141.           Obtain the number of CPUs configured on the system
  142.  
  143.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_CCCC_PPPP_UUUU_LLLL_iiii_ssss_tttt(3x)
  144.           Get the list of all CPUs assigned to a cpuset
  145.  
  146.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_NNNN_aaaa_mmmm_eeee(3x)
  147.           Get the name of the cpuset to which a process is attached
  148.  
  149.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_NNNN_aaaa_mmmm_eeee_LLLL_iiii_ssss_tttt(3x)
  150.           Get a list names for all defined cpusets
  151.  
  152.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_PPPP_IIII_DDDD_LLLL_iiii_ssss_tttt(3x)
  153.           Get a list of all PIDs attached to a cpuset
  154.  
  155.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_PPPP_rrrr_oooo_pppp_eeee_rrrr_tttt_iiii_eeee_ssss(3x)
  156.           Get various properties of an existing cpuset.
  157.  
  158.      _cccc_pppp_uuuu_ssss_eeee_tttt_AAAA_llll_llll_oooo_cccc_QQQQ_uuuu_eeee_uuuu_eeee_DDDD_eeee_ffff(3x)
  159.           Allocate a cpuset_QueueDef_t structure
  160.  
  161.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_PPPP_rrrr_oooo_pppp_eeee_rrrr_tttt_iiii_eeee_ssss(3x)
  162.           Release memory used by a cpuset_Properties_t structure
  163.  
  164.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_QQQQ_uuuu_eeee_uuuu_eeee_DDDD_eeee_ffff(3x)
  165.           Release memory used by a cpuset_QueueDef_t structure
  166.  
  167.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_CCCC_PPPP_UUUU_LLLL_iiii_ssss_tttt(3x)
  168.           Release memory used by a cpuset_CPUList_t structure
  169.  
  170.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_NNNN_aaaa_mmmm_eeee_LLLL_iiii_ssss_tttt(3x)
  171.           Release memory used by a cpuset_NameList_t structure
  172.  
  173.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_PPPP_IIII_DDDD_LLLL_iiii_ssss_tttt(3x)
  174.           Release memory used by a cpuset_PIDList_t structure
  175.  
  176. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  177.      This example creates a cpuset named "myqueue" containing CPUs 4, 8, and
  178.      12.  The example uses the interfaces in the cpuset library,
  179.      _////_llll_iiii_bbbb_3333_2222_////_llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo, if they are present.  If the interfaces are not
  180.      present, it attempts to use the _c_p_u_s_e_t(1) command to create the cpuset.
  181.  
  182.                #include <cpuset.h>
  183.                #include <stdio.h>
  184.                #include <errno.h>
  185.  
  186.                #define PERMFILE "/usr/tmp/permfile"
  187.  
  188.                int
  189.                main(int argc, char **argv)
  190.                {
  191.                    cpuset_QueueDef_t *qdef;
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  203.  
  204.  
  205.  
  206.                    char              *qname = "myqueue";
  207.                    FILE              *fp;
  208.  
  209.                    /* Alloc queue def for 3 CPU IDs */
  210.                    if (_MIPS_SYMBOL_PRESENT(cpusetAllocQueueDef)) {
  211.                        printf("Creating cpuset definition\n");
  212.                        qdef = cpusetAllocQueueDef(3);
  213.                        if (!qdef) {
  214.                            perror("cpusetAllocQueueDef");
  215.                            exit(1);
  216.                        }
  217.  
  218.                        /* Define attributes of the cpuset */
  219.                        qdef->flags = CPUSET_CPU_EXCLUSIVE
  220.                                    | CPUSET_MEMORY_LOCAL
  221.                                    | CPUSET_MEMORY_EXCLUSIVE;
  222.                        qdef->permfile = PERMFILE;
  223.                        qdef->cpu->count = 3;
  224.                        qdef->cpu->list[0] = 4;
  225.                        qdef->cpu->list[1] = 8;
  226.                        qdef->cpu->list[2] = 12;
  227.                    } else {
  228.                        printf("Writing cpuset command config"
  229.                                " info into %s\n", PERMFILE);
  230.                        fp = fopen(PERMFILE, "a");
  231.                        if (!fp) {
  232.                            perror("fopen");
  233.                            exit(1);
  234.                        }
  235.                        fprintf(fp, "EXCLUSIVE\n");
  236.                        fprintf(fp, "MEMORY_LOCAL\n");
  237.                        fprintf(fp, "MEMORY_EXCLUSIVE\n\n");
  238.                        fprintf(fp, "CPU 4\n");
  239.                        fprintf(fp, "CPU 8\n");
  240.                        fprintf(fp, "CPU 12\n");
  241.                        fclose(fp);
  242.                    }
  243.  
  244.                    /* Request that the cpuset be created */
  245.                    if (_MIPS_SYMBOL_PRESENT(cpusetCreate)) {
  246.                        printf("Creating cpuset = %s\n", qname);
  247.                        if (!cpusetCreate(qname, qdef)) {
  248.                            perror("cpusetCreate");
  249.                            exit(1);
  250.                        }
  251.                    } else {
  252.                        char command[256];
  253.  
  254.                        fprintf(command, "/usr/sbin/cpuset -q %s -c"
  255.                               "-f %s", qname,
  256.                               PERMFILE);
  257.                        if (system(command) < 0) {
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  269.  
  270.  
  271.  
  272.                            perror("system");
  273.                            exit(1);
  274.                        }
  275.                    }
  276.  
  277.                    /* Free memory for queue def */
  278.                    if (_MIPS_SYMBOL_PRESENT(cpusetFreeQueueDef)) {
  279.                        printf("Finished with cpuset definition,"
  280.                                " releasing memory\n");
  281.                        cpusetFreeQueueDef(qdef);
  282.                    }
  283.  
  284.                    return 0;
  285.                }
  286.  
  287.  
  288.      This example shows how to create a replacement library for
  289.      _////_llll_iiii_bbbb_3333_2222_////_llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo so that a program built to use the cpuset library
  290.      interfaces will execute if the library is not present.
  291.  
  292.        1. The file replace.c is created, and contains the following line of
  293.        code:
  294.  
  295.                  static void cpusetNULL(void) { }
  296.  
  297.  
  298.        2. The file replace.c is compiled:
  299.  
  300.                  cc -mips3 -n32 -c replace.c
  301.  
  302.  
  303.        3. The object replace.o created in the previous step is placed in a
  304.        library:
  305.  
  306.                  ar ccrl libcpuset.a replace.o
  307.  
  308.  
  309.        4. The library is converted into a DSO:
  310.  
  311.                  ld -mips3 -n32 -quickstart_info -nostdlib        \
  312.                      -elf -shared -all -soname libcpuset.so       \
  313.                      -no_unresolved -quickstart_info -set_version \
  314.                      sgi1.0 libcpuset.a -o libcpuset.so
  315.  
  316.  
  317.        5. The DSO is installed on the system:
  318.  
  319.                  install -F /opt/lib32 -m 444 -src libcpuset.so \
  320.                      libcpuset.so
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  335.  
  336.  
  337.  
  338.      The replacement library can be installed in a directory defined by the
  339.      LD_LIBRARYN32_PATH environment variable (see _r_l_d(1)).  If the replacement
  340.      library must be installed in a directory that is in the default search
  341.      path for shared libraries, it should be installed in _////_oooo_pppp_tttt_////_llll_iiii_bbbb_3333_2222.
  342.  
  343. NNNNOOOOTTTTEEEESSSS
  344.      In a cluster environment, the cpuset configuration file should reside on
  345.      the root filesystem.  If the cpuset configuration file resides on a
  346.      filesystem other than the root filesystem and  you attempt to unmount the
  347.      filesystem, the vnode for the cpuset remains active and the _uuuu_nnnn_mmmm_oooo_uuuu_nnnn_tttt (see
  348.      _uuuu_nnnn_mmmm_oooo_uuuu_nnnn_tttt(1M) command fails.
  349.  
  350. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  351.      cpuset(1), cpusetAllocQueueDef(3x), cpusetAttach(3x),
  352.      cpusetAttachPID(3x), cpusetCreate(3x), cpusetDestroy(3x),
  353.      cpusetDetachAll(3x), cpusetDetachPID(3x), cpusetFreeCPUList(3x),
  354.      cpusetFreeNameList(3x), cpusetFreePIDList(3x), cpusetFreeProperties(3x),
  355.      cpusetGetCPUCount(3x), cpusetGetCPUList(3x), cpusetGetName(3x),
  356.      cpusetGetNameList(3x), cpusetGetPIDList(3x), cpusetGetProperties(3x),
  357.      cpuset(4).
  358.  
  359.      _I_R_I_X _A_d_m_i_n: _R_e_s_o_u_r_c_e _A_d_m_i_n_i_s_t_r_a_t_i_o_n
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.